package BNS.plumbing;

import javax.swing.JComponent;
/**<p>
	Classes implementing this interface must support whatever GUI elements 
	the BNS player needs, and interact with the Remote game interface residing 
	on the server to execute his requests. The contract between the game's
	controller and the Persona(s) must be given in an interface (of the user's
	design) that extends Remote. See BNSGameController.
</p><p>
	Objects of this class will be constructed on the server but executed 
	on a client; arbitrary information can be embedded in it before it gets 
	sent to the client.
	In particular, the remote game object and the nodeID should be obtained 
	through an argument to the constructor for this class. That call to the 
	constructor occurs in the SessionHost.
</p><p>
	An implementation of BNSPersona will run on the client machine in its own Thread.
	Changes in the BNS game will be evident when a different thread 
	(also living in the BNS.Client) calls the update method. 
</p><p>
	The thread that calls update() may be used to change the display of information; 
	the thread that calls run() should be used to handle human input and make requests 
	on the BNS game object. This separation of responsibilities allows the BNS system 
	to optimize network communication performance. 
	*/
public abstract class BNSPersona implements java.io.Serializable {
	
	/**
	 * 
	 */
	//private static final long serialVersionUID = 1L;

	/** To create the GUI, this method must be called. There is no reason to
		call this before it gets transported to the client environment and it is time
		to run it. Use a constructor to populate this object with data; the Client will
		call this method to set it up and make it go. 
		*/
	public abstract JComponent startPanel();
	
	/** This retrieves the same panel that was created by startPanel().
		It is available so that it can be removed from the client when finished. 
		TODO: get rid of this?
		*/
	public abstract JComponent killPanel();
	
	/** After the client obtains state information from the game object, 
		it will report the results to the BNSPersona by calling its gameUpdate() method. 
		The thread that calls this method may be used to refresh all the state 
		information being supplied to the player. 
		@param dataBlob the datastructure that is returned by the game's getUpdate
		method. It must be cast to the appropriate type, the details of which are unknown to 
		either the SessionHost or the BNSClient (and which perform the transport of the data). 
		*/
	public abstract void gameUpdate(java.io.Serializable dataBlob);
	
	/** returns the number of milliseconds that the Client is invited to delay between
		polls of the server to get updates to the game state. This is a nominal guideline;
		each Client will separately attempt to adjust its actual delay time to accommodate 
		variations in communication and CPU time so that everyone has approximately this
		amount of turnaround time. Making this lower improves responsiveness; making it lower
		decreases demands on the server CPU and communication channels. */
	public int getCycleTime() { return 1000; }
	
	/** returns the name of this Persona 
		(i.e. the type of BNS game it is built to support). 
		TODO: make this a static final field? */
	public String getTitle() { return "an Implementation of BNSPersona"; }
	
	/** returns the identifying node of this Persona. */
	public BNS.graphs.Node getEigenNode() { return null; }
	
	/** The client will call this to request the Persona to start its activities. 
		TODO: get rid of this?
		*/
	public void start() {}
	
	/** Causes the Persona to stop its activities and terminate. 
		TODO: get rid of this?
		*/
	public void stop() {}
	
	}
